// Do not use //-style comments.  Following //-style comments are part of the
// style guide.
//
// Do not add blank lines at the beginning of a file.
//
// The line limit is 80 characters. Do not exceed 80 characters.
//
// Use two space characters per indentation level.
//
// Start the file with a @file documentation block and place the file into an
// appropriate @ingroup. Use CamelCase for documentation groups to
// avoid name conflicts. Do not use CamelCase for anything else.
/**
 * @file
 *
 * @ingroup Foobar
 *
 * @brief Foobar API in Initial Caps.
 */
// Use exactly one blank line between comment blocks. If you use a blank line,
// then use exactly one. Do not bloat the file with multiple blank lines in a
// sequence.

// Use an appropriate license header.
/*
 *  Copyright (C) 2012 Copyright Holder.
 *
 *  The license and distribution terms for this file may be
 *  found in the file LICENSE in this distribution or at
 *  http://www.rtems.com/license/LICENSE.
 */

// Use a header guard that assembles at least the include path of the file.
// Here for example <baz/caboom/foobar.h>.
#ifndef BAZ_CABOOM_FOOBAR_H
#define BAZ_CABOOM_FOOBAR_H

// Place your include files here.
#include <path/to/header.h>

// Use extern C declarations for C++.  Place it after include files.
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

// Put your API into a documentation group.
/**
 * @defgroup Foobar Foobar API
 *
 * @ingroup UpperLevelGroup
 *
 * @brief The foobar module performs some stuff.
 *
 * Use complete sentences in the documentation.  Exceptions to this are group
 * names and file @brief statements.
 *
 * @{
 */

/**
 * @brief A foobar type.
 *
 * Use a module prefix followed by a '_' in all names.  Here the module is
 * foobar.
 */
typedef some_other_type foobar_this_is_a_foobar_type;

/**
 * @brief The foobar object.
 *
 * Use a typedef for structs.  Do not use *_t names.  They are reserved by
 * POSIX.
 */
typedef struct {
  /**
   * @brief Some value used for something.
   */
  int some_value;
} foobar_object;

// Do not document forward declarations.  Use identical names for the typedef
// and the struct.
typedef struct foobar_type_with_forward_declaration
  foobar_type_with_forward_declaration;

/**
 * @brief Documentation for the forward declaration type.
 */
struct foobar_type_with_forward_declaration {
  /**
   * @brief Some other value used for something.
   */
  int some_other_value;
};

/**
 * @brief Demonstrates a function without arguments.
 *
 * Place the function name on the same line as the return type.
 *
 * Use space after the opening brace and before the closing brace of the
 * function prototype.
 */
int foobar_a_function_with_void_arguments( void );

/**
 * @brief Performs some stuff.
 *
 * Start the brief description with the descriptive verb in the simple present
 * tense.
 *
 * @param[in] argument The argument is used to perform some stuff.  Use a
 * complete sentence for the argument description. Notice there is no period
 * after the variable name.
 */
void foobar_a_short_function_with_an_argument( int argument );

/**
 * @brief Does a lot of stuff with the arguments.
 *
 * Indent the arguments one level when the declaration exceeds 80 characters.
 * Place the closing parenthesis on a single line.
 *
 * Align the argument names.
 *
 * @param[in] pass_by_value_argument The pass by value argument.
 * @param[in] input_reference_argument The input argument passed by reference.
 * @param[out] output_reference_argument The output argument passed by
 * reference.
 * @param[in, out] input_and_output_reference_argument The input and output
 * argument passed by reference.
 */
void foobar_a_function_with_a_lot_of_arguments(
  int        pass_by_value_argument,
  const int *input_reference_argument,
  int       *output_reference_argument,
  int       *input_and_output_reference_argument
);

/**
 * @brief Creates something.
 *
 * Use @see to reference related functions.  For example if you create an
 * object, then you are probably interested in destroying it as well.
 *
 * For a pointer return value, put the asterisk next to the function name.
 *
 * @see foobar_destroys_something().
 */
foobar_object *foobar_creates_something( void );

/**
 * @brief Creates something in the best case.
 *
 * Use @retval for return values.
 *
 * @retval NULL Not enough resources.  Use a complete sentence for the return
 * value description.
 * @retval other Pointer to the created object.
 */
foobar_object *foobar_creates_something_in_the_best_case( void );

// Terminate the documentation group.
/** @} */

// Terminate the extern C declarations for C++.
#ifdef __cplusplus
}
#endif /* __cplusplus */

// Terminate the header guard.
#endif /* BAZ_CABOOM_FOOBAR_H */
// Do not add blank lines at the end of a file.
